Guia de Solução de Problemas e Boas Práticas: Emissão de NF-e/NFC-e (RTC)

Este guia é um recurso completo para desenvolvedores e usuários que estão integrando seus sistemas com nossa API de emissão de NF-e/NFC-e. Ele aborda desde os erros mais comuns até as especificidades da Reforma Tributária (RTC), além de fornecer boas práticas e tabelas de referência para garantir uma integração suave e eficiente.

Se você está começando, recomendamos ler a seção de Boas Práticas de Integração antes de iniciar o desenvolvimento.

---

1. Rejeições Comuns (Gerais)

Esta seção cobre os erros mais frequentes que não estão diretamente ligados à Reforma Tributária.

Rejeição 204: Duplicidade de NF-e

• O que significa: Já existe uma nota com o mesmo número, série e CNPJ do emitente na base da SEFAZ.
• Causa Comum: Tentativa de reenvio de uma nota já autorizada ou em processamento, ou erro no controle de numeração sequencial.
• Como Resolver: Verifique o status da nota original. Se já estiver autorizada, não reenvie. Se precisar emitir uma nova nota, incremente o campo number para o próximo valor disponível na sequência da serie.

Rejeição 225: Falha no Schema XML

• O que significa: A estrutura do JSON enviado não corresponde ao layout esperado pela API, resultando em um XML inválido para a SEFAZ.
• Causa Comum: Campos com tipos de dados incorretos (ex: enviar texto onde se espera número), nomes de propriedades errados ou estrutura de objetos aninhados incorreta.
• Como Resolver: Revise o corpo da requisição e compare com a especificação OpenAPI e os exemplos da documentação funcional. Dê atenção especial aos tipos de dados e à hierarquia dos objetos.

Rejeição 210: IE do destinatário inválida

• O que significa: A Inscrição Estadual (stateTaxNumber) informada para o comprador (buyer) não é válida para o estado de destino.
• Causa Comum: Erro de digitação, IE inexistente ou IE de outro estado diferente do endereço do comprador.
• Como Resolver: Confirme a Inscrição Estadual correta do destinatário. Se o destinatário for isento ou não contribuinte, ajuste o campo stateTaxNumberIndicator para Exempt (Isento) ou NonTaxPayer (Não Contribuinte) e não envie o campo stateTaxNumber.

Rejeição 539: Duplicidade de NF-e com diferença na Chave de Acesso

• O que significa: Você tentou emitir uma nota com o mesmo number e serie de uma nota anterior, mas com algum dado diferente (data, valor, cliente), o que gerou uma chave de acesso nova.
• Como Resolver: A numeração é única. Se a nota anterior foi autorizada, você deve usar o próximo número sequencial. Se a nota anterior não serve, ela deve ser cancelada (se estiver no prazo) ou você deve emitir uma nova nota com um novo número.

Rejeição 610: Total da NF-e difere do somatório dos valores que compõem o valor total

• O que significa: O campo totals.icms.invoiceAmount não corresponde à soma dos valores dos itens e demais campos que compõem o total.
• Causa Comum: Erro de cálculo no somatório de items.totalAmount mais frete, seguro, despesas acessórias, impostos e subtração de descontos.
• Como Resolver: Recalcule o valor total da nota. A fórmula básica é: vProd (soma de totalAmount dos itens) - vDesc + vST + vFrete + vSeg + vOutro + vIPI + vIPIDevol. Com a RTC, o campo totalInvoiceAmount também deve ser validado, incluindo os novos impostos.

Rejeição 321: NF-e de devolução de mercadoria não possui documento fiscal referenciado

• O que significa: A nota foi emitida com finalidade de Devolução (purposeType = Devolution), mas não foi informada a chave de acesso da nota original que está sendo devolvida.
• Causa Comum: Esquecimento de preencher o grupo additionalInformation.taxDocumentsReference.
• Como Resolver: Adicione o grupo taxDocumentsReference dentro de additionalInformation, contendo um objeto documentElectronicInvoice com a accessKey da NF-e que originou a devolução.

Rejeição 703: Data-Hora de Emissão posterior ao horário de recebimento

• O que significa: A data/hora enviada no campo operationOn está no futuro em relação ao relógio da SEFAZ.
• Causa: Relógio do servidor adiantado ou configuração incorreta de Fuso Horário (Timezone).
• Solução: Verifique o relógio do servidor e certifique-se de enviar o offset do fuso horário correto (ex: -03:00) no formato da data.

Rejeição 520: CFOP de Operação com Exterior e UF destinatária diferente de "EX"

• O que significa: Foi usado um CFOP iniciado em 7 (exportação), mas o endereço do destinatário é no Brasil.
• Solução: Se é uma operação de exportação, o estado (state) do destinatário deve ser "EX". Se for uma venda interna, corrija o CFOP para um código iniciado em 5 (operação estadual) ou 6 (operação interestadual).

Rejeição 778: NCM Inexistente

• O que significa: O código NCM informado no produto não existe mais na tabela oficial do governo.
• Causa: A Receita Federal atualiza periodicamente a tabela TIPI, extinguindo códigos antigos e criando novos.
• Solução: Atualize o cadastro do produto com um NCM válido e vigente. Consulte a tabela TIPI mais recente.

Situação Comum: Confusão de Ambientes (Homologação vs. Produção)

• Sintoma: "A API retornou que a nota foi autorizada, mas não consigo consultá-la no Portal da SEFAZ."
• Causa: A nota foi emitida no ambiente de Homologação (Teste), mas a consulta está sendo feita no portal de Produção.
• Solução: Notas emitidas em homologação não têm validade jurídica e não aparecem na consulta pública principal. Certifique-se de que está consultando no ambiente correto ou mude a configuração da API para Production se desejar emitir uma nota real.

---

2. Rejeições da Reforma Tributária (RTC)

Erros específicos do novo modelo de tributação (IBS, CBS, IS).

Rejeição 1115: IBS/CBS não informado

• O que significa: Para uma operação no novo regime, o grupo IBSCBS não foi informado em um ou mais itens.
• Causa Comum: A operação já se enquadra nas regras da RTC, mas o sistema emissor ainda não está enviando o grupo items.tax.IBSCBS.
• Como Resolver: Para cada item da nota, adicione o objeto IBSCBS dentro de tax, preenchendo os campos obrigatórios como situationCode, classCode, basis e os subgrupos state, municipal e cbs.

Rejeição 1023: Classificação Tributária IBS/CBS informada inexistente

• O que significa: O código informado em items.tax.IBSCBS.classCode não existe na tabela oficial cClassTrib da SEFAZ.
• Causa Comum: Erro de digitação ou uso de código desatualizado.
• Como Resolver: Consulte o Apêndice B deste guia ou a tabela cClassTrib mais recente no Portal Nacional da NF-e e utilize um código válido.

Rejeição 1024: Classificação Tributária IBS e CBS incompatível com o CST informado

• O que significa: A combinação entre situationCode (CST) e classCode (Classificação Tributária) não é permitida.
• Causa Comum: Um classCode que representa isenção foi combinado com um situationCode de tributação integral, por exemplo.
• Como Resolver: Verifique o Apêndice B deste guia. Ele contém as combinações válidas entre CST e Classificação Tributária. Ajuste um dos dois campos para que a combinação seja válida.

Rejeição 1104: Valor da base de cálculo do IBS e CBS difere do somatório dos valores que a compõem

• O que significa: O valor informado em items.tax.IBSCBS.basis não corresponde à soma dos valores que formam a base de cálculo do item.
• Causa Comum: Erro no cálculo da base, que geralmente é vProd - vDesc + vFrete + vSeg + vOutro + vII + vIPI.
• Como Resolver: Recalcule o campo basis de cada item, garantindo que ele reflita o somatório correto dos valores que compõem a base de cálculo para os novos impostos.

Rejeição 1026: Alíquota do IBS Estadual inválida

• O que significa: A alíquota do IBS estadual (items.tax.IBSCBS.state.rate) não corresponde à alíquota vigente para o período de emissão.
• Causa Comum: Uso de alíquota incorreta. No período de transição, as alíquotas são fixas (ex: 0,1% para 2025/2026).
• Como Resolver: Ajuste a alíquota para o valor correto definido na legislação da Reforma Tributária para o ano de emissão da nota. Consulte a documentação para os valores vigentes.

Rejeição 1027: Alíquota do IBS Municipal inválida

• O que significa: A alíquota do IBS municipal (items.tax.IBSCBS.municipal.rate) não corresponde à alíquota vigente para o período de emissão.
• Causa Comum: Uso de alíquota incorreta. No período de transição, as alíquotas são fixas (ex: 0,8% para 2025/2026).
• Como Resolver: Ajuste a alíquota para o valor correto definido na legislação da Reforma Tributária para o ano de emissão da nota.

Rejeição 1001: NF-e com finalidade de débito ou crédito apenas para IBS/CBS

• O que significa: Uma nota com finalidade de Débito (purposeType = Debit) ou Crédito (purposeType = Credit) continha grupos de impostos do regime antigo (ICMS, IPI, PIS, COFINS).
• Causa Comum: Envio de nota de ajuste de impostos da RTC contendo indevidamente impostos do modelo antigo.
• Como Resolver: Remova completamente os grupos icms, ipi, pis, cofins e icmsDestination do objeto tax de todos os itens da nota. Notas de débito e crédito são exclusivamente para ajustes de IBS e CBS.

Rejeição 1200: Total da NF-e (RTC) difere do somatório dos valores

• O que significa: O campo totals.totalInvoiceAmount não corresponde à soma do valor total do regime antigo (totals.icms.invoiceAmount) com os novos impostos (totals.isTotals.amount e os totais de totals.ibsCbsTotals).
• Causa Comum: Erro de cálculo no valor total final da nota, que deve considerar tanto os tributos do regime antigo (se houver) quanto os do novo regime.
• Como Resolver: Recalcule o valor total da nota. A fórmula é: vNF (regime antigo) + vIS + vIBS + vCBS. Garanta que o campo totalInvoiceAmount reflita essa soma.

Rejeição 1116: Modo de cálculo automático do IBS/CBS com preenchimento indevido

• O que significa: O campo calculationMode foi definido como OfficialService, mas outros campos de tributo do grupo IBSCBS (como basis, rate ou amount) também foram preenchidos.
• Causa Comum: Envio de dados desnecessários ao optar pelo cálculo automático.
• Como Resolver: Ao usar calculationMode: "OfficialService", envie apenas os campos situationCode e classCode dentro do grupo IBSCBS. Remova todos os outros campos de valores e alíquotas (basis, state, municipal, cbs, etc.), pois eles serão calculados e preenchidos pelo serviço oficial.

Exemplo Incorreto:

{
  "purposeType": "Credit",
  "creditType": "valueReduction",
  "items": [
    {
      "tax": {
        "icms": { "origin": "0", "cst": "90" }, // INCORRETO: Grupos do regime antigo não permitidos
        "IBSCBS": { ... }
      }
    }
  ]
}

Exemplo Correto:

{
  "purposeType": "Credit",
  "creditType": "valueReduction",
  "items": [
    {
      "tax": {
        "IBSCBS": { ... } // CORRETO: Apenas o grupo IBSCBS é informado
      }
    }
  ]
}

---

3. Guia Passo a Passo: Tratando Erros Comuns

3.1. Rejeição 204: Duplicidade de NF-e

A rejeição 204 é uma das mais comuns e indica que a SEFAZ já recebeu uma nota com a mesma chave de acesso ou com o mesmo número e série para o emitente. Siga este fluxo para resolver:

Passo 1: Verificar o Status da Nota Original

Antes de tentar emitir uma nova nota ou incrementar a numeração, descubra o status da nota que causou a duplicidade.

1. Consulte a nota: Consulte o webhook encaminhado pelo nosso sistema ou utilize o endpoint de consulta da API para buscar a nota pelo ID.
2. Analise o Retorno:
   • Autorizada: Se a nota já consta como Issued, o envio anterior teve sucesso. Ação: Atualize o status no seu sistema e capture o XML/DANFE. Não reenvie.
   • Cancelada: A nota existe, mas foi cancelada. Ação: O número não pode ser reutilizado. Emita uma nova nota com um novo número (number).
   • Denegada: A nota existe e foi denegada por irregularidade fiscal. Ação: O número não pode ser reutilizado. Resolva a pendência fiscal e emita uma nova nota com novo número.

Passo 2: Decidir sobre a Numeração

Se a consulta não retornar uma nota autorizada, mas a rejeição 204 persistir ao tentar enviar:

• Cenário A (Correção): Se a nota original foi rejeitada (não autorizada), teoricamente o número poderia ser reutilizado. Se a SEFAZ acusa duplicidade, pode haver uma nota autorizada que seu sistema desconhece. Consulte a chave diretamente no Portal da SEFAZ para ter certeza.
• Cenário B (Nova Emissão): Se você precisa emitir com urgência ou não consegue recuperar o status da anterior, a solução é usar um novo número.
  • Ação: Incremente o campo number para o próximo sequencial disponível e envie a requisição novamente.

Passo 3: Inutilizar a Numeração (Se necessário)

Se você optou por pular a numeração (Cenário B) e emitiu a nota com número seguinte (ex: pulou a 100 e emitiu a 101), criou-se uma quebra na sequência.

1. Identifique o número pulado: No exemplo, o número 100.
2. Confirme o não-uso: Certifique-se de que a nota 100 realmente não foi autorizada, cancelada ou denegada.
3. Solicite a Inutilização: Envie uma requisição de inutilização para a API informando:
   • serie: A série da nota.
   • beginNumber e endNumber: O número ou faixa a ser inutilizada (ex: 100).
   • reason: Justificativa (ex: "Ocorrência de erro técnico na emissão").

---

4. Procedimentos Fiscais: Cancelamento, Inutilização e Devolução

É comum haver dúvidas sobre qual procedimento adotar para corrigir ou anular uma operação fiscal. Abaixo esclarecemos a diferença entre os três principais mecanismos.

4.1. Cancelamento

• O que é: Ato de invalidar uma NF-e autorizada, tornando-a sem efeito fiscal.
• Quando usar: Quando a operação comercial não se concretizou (ex: desistência da compra) e, crucialmente, a mercadoria ainda não circulou.
• Regras Principais:
  • Deve ser solicitado dentro do prazo legal, geralmente 24 horas após a autorização.
  • A mercadoria não pode ter saído do estabelecimento emitente.
  • O destinatário não pode ter realizado a "Ciência da Emissão".

4.2. Inutilização de Numeração

• O que é: Processo de comunicar à SEFAZ que uma faixa de números de NF-e não foi e não será utilizada.
• Quando usar: Quando há um salto na sequência da numeração das notas. Exemplo: a nota 100 foi emitida e a próxima a ser emitida é a 102, ficando o número 101 vago.
• Regras Principais:
  • A inutilização aplica-se apenas a números que não foram usados em nenhuma NF-e (nem mesmo em nota rejeitada ou denegada).
  • Serve para o Fisco saber que o "buraco" na sequência não é sonegação, mas uma falha técnica ou operacional.

4.3. Nota de Devolução

• O que é: Emissão de uma nova NF-e (com purposeType = Devolution) para anular os efeitos de uma operação anterior.
• Quando usar: Quando a mercadoria circulou e o destinatário a está devolvendo, seja por recusa no recebimento ou devolução após entrega. É a única forma de anular uma operação após a circulação da mercadoria.
• Regras Principais:
  • É uma nota de entrada (operationType = Incoming) para o emitente original.
  • Deve referenciar a chave de acesso da NF-e original que está sendo devolvida.
  • Os impostos são "espelhados" para anular o débito da nota de saída.

---

5. Boas Práticas de Integração e Checklist

Esta seção detalha as recomendações para garantir uma integração mais eficiente, robusta e resiliente com a API.

5.1. Boas Práticas Detalhadas

Controle de Numeração e Série

• O controle da numeração sequencial (number) para cada série (serie) é fundamental para evitar a "Rejeição 204: Duplicidade de NF-e".
• O controle pode ser realizado de duas formas: pelo cliente, enviando os campos serie e number na requisição, ou automaticamente pelo nosso sistema.
• Para o controle automático, o usuário pode definir o valor inicial da série e do número no cadastro da Inscrição Estadual. Se os campos serie e number não forem enviados na requisição, nosso sistema gerenciará a sequência.
• Atenção: Se o controle for realizado pelo nosso sistema, o número de uma nota fiscal que resultar em erro não será reaproveitado. Nesse caso, o cliente deverá gerenciar a quebra de numeração para inutilizar os números pulados posteriormente.
• O sistema cliente deve sempre verificar a ocorrência de pulos na sequência numérica. Caso um número não seja utilizado, é necessário solicitar a sua inutilização para evitar problemas com o Fisco.
• Sempre que for necessário alterar ou iniciar o uso de uma nova série fiscal, é mandatório que o cadastro da Inscrição Estadual do emitente seja previamente atualizado no sistema.

Validação de Dados Pré-Envio

• Reduza chamadas desnecessárias: Antes de enviar os dados para a API, realize o máximo de validações possível no seu sistema.
• Valide dados cadastrais e de endereço: Use APIs de consulta para verificar CNPJs, CPFs, Inscrições Estaduais e CEPs, evitando rejeições por dados incorretos.
• Garanta que campos obrigatórios estão preenchidos de acordo com a operação (ex: CFOP, NCM).

Tratamento de Erros e Rejeições

• Utilize os logs detalhados de requisições (JSON enviado) e respostas (JSON recebido) para análise e depuração em caso de erros.
• Para erros de rede ou instabilidade momentânea da SEFAZ (ex: timeouts, erros 5xx), nosso sistema já possui um mecanismo de retentativa com exponential backoff, não sendo necessário implementar essa lógica no cliente.

Gerenciamento do Ciclo de Vida da NF-e

• Utilize webhooks para receber notificações automáticas sobre o status final da nota ('Emitida', 'Erro'), em vez de realizar consultas periódicas.
• Nosso sistema armazena o XML de cada NF-e autorizada por no mínimo 5 anos. O download do XML e DANFE está disponível a qualquer momento.
• Esteja preparado para a contingência. O modo de emissão em contingência pode ser configurado em nossa plataforma para gerenciamento automático, permitindo que sua operação continue sem interrupções.

Performance e Eficiência

• Mantenha uma cópia local e atualizada das tabelas de referência (NCM, CEST, CFOP, cClassTrib, etc.).
• Envie apenas os campos e grupos necessários para a sua operação, omitindo grupos opcionais não aplicáveis para um payload mais limpo e validação mais rápida.

Segurança

• Trate as chaves de acesso à API (API Keys) e os certificados digitais como informações altamente sensíveis. Não as exponha no código-fonte do lado do cliente (frontend) e armazene-as de forma segura no seu backend.

5.2. Checklist Rápido de Integração

• Validação Pré-Envio: Implementar validações no seu sistema para campos obrigatórios (CFOP, NCM, etc.) antes de enviar a requisição para a API.
• Consulta de Cadastros: Utilizar APIs de consulta para validar dados de CNPJ, CPF, Inscrição Estadual e endereços (via CEP).
• Cache de Tabelas Auxiliares: Manter uma cópia local e atualizada das tabelas de referência (NCM, CEST, CFOP, e as novas tabelas da RTC como cClassTrib).
• Controle de Numeração: Definir a estratégia de controle de numeração sequencial (number) e série (serie) para evitar a Rejeição 204.
• Tratamento de "Pulos" na Numeração: Implementar um processo para solicitar a inutilização de números que não foram utilizados.
• Gerenciamento de Status com Webhooks: Configurar um endpoint (webhook) para receber notificações de status em tempo real (Emitida, Erro, Cancelada).
• Estratégia de Contingência: Configurar o modo de contingência automático na plataforma ou preparar o sistema para gerenciá-lo.
• Payloads Otimizados: Enviar na requisição apenas os campos e grupos necessários para a operação.
• Proteção de Credenciais: Armazenar as chaves de acesso da API e os certificados digitais de forma segura no backend.
• Implementar Fluxos de Correção: Preparar o sistema para os eventos pós-emissão, como Cancelamento, Carta de Correção (CC-e) e emissão de Nota de Devolução.

---

6. Apêndices

6.1. Apêndice A: Mapeamento de Grupos (JSON para XML)

Para desenvolvedores familiarizados com o layout XML da SEFAZ, a tabela abaixo resume o mapeamento dos principais grupos do JSON da API.

Grupo na API (JSON)	Grupo no XML (SEFAZ)	Descrição
(raiz do objeto)	ide	Identificação da NF-e
issuer	emit	Dados do Emitente
buyer	dest	Dados do Destinatário
delivery	entrega	Local de Entrega
withdrawal	retirada	Local de Retirada
items	det	Detalhamento de Produtos e Serviços (Itens)
items.tax	imposto	Tributos incidentes no item
items.tax.icms	ICMS	Grupo de ICMS
items.tax.ipi	IPI	Grupo de IPI
items.tax.pis	PIS	Grupo de PIS
items.tax.cofins	COFINS	Grupo de COFINS
items.tax.IS	IS	Grupo do Imposto Seletivo (RTC)
items.tax.IBSCBS	IBSCBS	Grupo de IBS e CBS (RTC)
totals	total	Grupo de Valores Totais
totals.icms	ICMSTot	Totais de ICMS
totals.issqn	ISSQNtot	Totais de ISSQN
totals.isTotals	ISTot	Totais do Imposto Seletivo (RTC)
totals.ibsCbsTotals	IBSCBSTot	Totais de IBS e CBS (RTC)
transport	transp	Dados do Transporte
billing	cobr	Dados da Cobrança (Fatura e Duplicatas)
payment	pag	Dados do Pagamento
additionalInformation	infAdic	Informações Adicionais
purchaseInformation	compra	Informações de Compra (empenho, pedido)
export	exporta	Informações de Exportação
transactionIntermediate	infIntermed	Informações do Intermediador da Transação

6.2. Apêndice B: Tabela de Referência - CST e Classificação Tributária (IBS/CBS)

A combinação correta do Código de Situação Tributária (situationCode) e do Código de Classificação Tributária (classCode) é essencial para a validação da NF-e no novo regime.

Código CST	Descrição CST	Código Class.	Descrição da Classificação Tributária
000	Tributação integral	000001	Situações tributadas integralmente pelo IBS e CBS.
000	Tributação integral	000002	Exploração de via, observado o art. 11 da Lei Complementar nº 214, de 2025.
010	Tributação com alíquotas uniformes - operações do FGTS	010001	Operações do FGTS não realizadas pela Caixa Econômica Federal...
011	Tributação com alíquotas uniformes reduzidas em 60%	011001	Planos de assistência funerária...
011	Tributação com alíquotas uniformes reduzidas em 60%	011002	Planos de assistência à saúde...
200	Alíquota zero	200001	Aquisições de máquinas, aparelhos, instrumentos... em zonas de processamento de exportação.
200	Alíquota zero	200003	Vendas de produtos da Cesta Básica Nacional de Alimentos.
200	Alíquota reduzida em 60%	200028	Fornecimento dos serviços de educação...
200	Alíquota reduzida em 30%	200052	Prestação de serviços de profissões intelectuais (advogados, arquitetos, etc.).
400	Isenção	400001	Fornecimento de serviços de transporte público coletivo...
410	Imunidade e não incidência	410002	Transferências entre estabelecimentos do mesmo contribuinte.
410	Imunidade e não incidência	410004	Exportações de bens e serviços.
510	Diferimento	510001	Operações com energia elétrica...
550	Suspensão	550001	Exportações de bens materiais.
620	Tributação monofásica	620001	Tributação monofásica sobre combustíveis.
800	Transferência de crédito	800001	Fusão, cisão ou incorporação.

Nota: A tabela acima é um extrato simplificado. Para a lista completa e detalhada, consulte a documentação oficial no Portal Nacional da NF-e.